# Management Console User Guide #
This section is a complete user guide to the *Service Gateway Management Console*. It also describes prerequisites and instructions for creating a Management Console website in *Microsoft Azure*.

## Prerequisites    
The *Service Gateway Management Console* is a website that runs in *Microsoft Azure Websites*. Creation of a new Management Console website is easy through the *Microsoft Azure Websites Gallery*, but before a new website can be created a number of prerequisites must be satisfied.

Authentication to the Management Console is similar to the rest of the Service Gateway in that it uses *Azure Active Directory (AAD)* as an identity provider. This allows *Active Directory* users from on-premise installations to be authenticated for use with this application. Additionally, *federated* users from other identity providers (eg. Facebook, Salesforce.com, etc.) may also be used. For more information on integration with *AAD*, see the [Authentication and Authorization](Auth) section of this documentation.

To enable users of the Management Console website to be able to authenticate and perform deployments to *Microsoft Azure* on their behalf, please ensure that all of the following steps are performed:

1. If not already available, create an *Azure Active Directory* using the [Microsoft Azure Management Portal](http://manage.windowsazure.com).  
![Create new Azure Active Directory](http://configtest.blob.core.windows.net/resources/codeplex/waad-new-tenant-step1.jpg) 
2. Enter a unique name for the Directory that represents your company's identity:  
![Create new Azure Active Directory](http://configtest.blob.core.windows.net/resources/codeplex/waad-new-tenant-step2.jpg)
3. Once a Directory is available, you may proceed with creating a Management Console website. However, you will be required to return to the *AAD* portal to configure an *Application* to enable access for the Management Console. 

## Creating a Service Gateway Management Console Website 

The Service Gateway Management Console is designed to run in the *Microsoft Azure Websites* environment. If you have downloaded the code and built the Console project you may deploy that project using any means available. To make the creation process easier the Management Console has been added to the *Microsoft Azure Websites Gallery* which provides a wizard guided experience to create a website.

To create a new Service Gateway Management Console website using the Gallery, first logon to the [Microsoft Azure Management Portal](http://manage.windowsazure.com). 

1.  In the *Microsoft Azure Portal* click the **New** button and navigate to website creation via Gallery:  
![Website Gallery Step 0](https://configtest.blob.core.windows.net/resources/codeplex/waws-gallery-create-step0.jpg)
2.  Select the **Tools** category and then click the **Service Gateway Management Console** entry:  
![Website Gallery Step 1](https://configtest.blob.core.windows.net/resources/codeplex/waws-gallery-create-step1.jpg)
3.  Enter a name for the URL for the new website. Select a database creation option (a database is required to save configuration and deployment details) and a region where you wish the website to be located.   
![Website Gallery Step 2](https://configtest.blob.core.windows.net/resources/codeplex/waws-gallery-create-step2.jpg)
4.  Next, enter and select details of the *SQL Azure* database that will be created to save Gateway information. It is generally a good idea to have to website and database co-exist in the same locality:  
![Website Gallery Step 3](https://configtest.blob.core.windows.net/resources/codeplex/waws-gallery-create-step3.jpg) 

## Using the Service Gateway Management Console Website  

### First Time Use
The Service Gateway Management Console has a startup mode where additional pieces of configuration information must be entered so that the application can be authorized to deploy items to *Microsoft Azure* on your behalf.

The first time that you navigate to the website after creating it, you will be shown the 'Startup' page which includes detailed instructions for configuring an **Application** in *AAD* that is required to authorize the application to sign-on and interact with Azure's Management API.

When you follow the instructions on the Startup page, you will then be prompted to sign-in to the application using your *AAD* user credentials. You must then enter two pieces of information that were generated with creating the **Application**. After this, the final pieces of configuration setup are automatically performed by the application and you are ready to start defining roles and deploying Gateways!


### Sign In and Out 
To sign into the application, click the **Sign In** link in the top-right on the heading banner. Enter the email address of a *Azure Active Directory* user from the Directory configured for use with the website (see above for creation configuration information) and the password. If the *AAD* tenant is configured for federated logon using *Active Directory Federation Services (ADFS)* the browser will automatically be redirected to the tenant's ADFS sign in page where the password may be entered. Upon successful entry of valid user credentials, the application will display the user's *User Principal Name (UPN)* to indicate the identity of the logged on user.

To sign out of the application, click on the drop-down link at the user's UPN and click **Sign Out**. The browser will be redirected to the *AAD* sign out page to sign out of all applications and then redirect back to the Management Console's home page.

If a user is logged on for an extended period of time (greater than 1 hour), you may notice the application redirecting to the *AAD* sign in page and then automatically returned. This is to allow the authenticated credentials to be refreshed and should be considered normal.

### Defining Roles
Clicking on the **Roles** tab will display a list of *Roles* defined for this Gateway. Roles represent independent components of an application that may exist at different locations and utilize different technology. Roles may also be *flighted* independently to enable multiple versions of the same component to be running in production at the same time.

To define a new Role, click the **Create New** link. Enter details for the name and location of the Role and click the **Create** button.

To modify an existing Role, click the **Details** link in the Index table next to the desired Role.

To delete an existing Role, click the **Delete** link in the Index table next to the desired Role. Again, Click the **Delete** button on the confirmation page to permanently delete the Role and all its associated information.

### Securing the Gateway Application
Authentication is a feature of the Service Gateway that relieves individual Roles of the requirement to implement. Authentication is implemented in the Gateway using *Azure Active Directory*. For full details of *AAD* integration with the Gateway, see the [Authentication and Authorization](Auth) section of the documentation.

To enable authentication for the Gateway, click the **Security** tab. Check the **Enable Authentication** check-box and click **Save**. Details of the *Application* that will be created in *AAD* to represent the Gateway website may be updated by clicking on the **Details** link (note that setting the App ID URI is an advanced feature. Use the default values unless absolutely necessary).

Note that when entering the **Security** tab for the first time, you may be prompted that the Management Console doesn't have sufficient access to deploy items to *Microsoft Azure*. This prompt will offer to enable this access with the current user's consent. For this consent to be effective, the currently signed on user must be a member of the **Global Administrators** role in the *AAD* Directory. If you are not a member of this Role, sign off from the website and get a user who is a Global Administrator to sign in and provide their consent. Once this consent has been successfully applied, it is no longer necessary to be a member of any particular role to configure or deploy the Service Gateway.

### Deploying the Service Gateway
Once the Role and Security configuration is correct, you may now proceed to deploy a Service Gateway to *Microsoft Azure*. To do this, click the **Deployments** tab and click the **Create New** link.

On the **Create Deployment** page, select the *Microsoft Azure* subscription that you would like to use to deploy the Gateway into. This drop-down list is populated with the subscriptions that the currently signed on user is an administrator or co-administrator for (and thus has permissions to deploy a hosted service). Enter a unique name that will form part of the URL for the gateway (eg. If you enter 'tripapp' in this field, the URL to access the Gateway and application will be http://*tripapp*.cloudapp.net). Custom domain names may be applied using DNS *CNAME* entries. Select the region where the Gateway should be deployed to. It is a generally good idea to co-locate as many of your application components to minimize network latency. Either enter details for a new storage account or select an existing storage account. A storage account is required to store diagnostic and analytic information, including IIS logs, Failed Request Tracing logs and advanced logs (which include pipeline timing information). These logs can be used for failure diagnostics as well as application analytics. Enter the number of instances for this Gateway deployment. 2 instances should be considered the lowest number as that provides a minimum level of redundancy to ensure the Gateway is always available. Additional instances should be provisioned as traffic demands require. 

Click the **Create** button to initiate the deployment of Service Gateway instances to *Microsoft Azure*. Progress of the deployment will be displayed as it progresses. Note: do not navigate away from this page until the deployment has completed - navigating away will not affect the deployment, but you will not be able to view the progress or any errors associated with the deployment.

### Enabling Application Analytics
Understanding the operation of an application by monitoring the 'ClickStream' logs is a well established practice for web properties. A large amount of information can be gleaned from the logs such as usage patterns, error rates, conversion/purchase rates, etc. The volume of entries in the ClickStream is so large, however, that it presents challenges to traditional RDBMS databases. New forms of scale-invariant processing, known as Map-Reduce, are now available as a better way of processing ClickStreams and thus gaining insight into application and user behavior.

The *Microsoft Azure HDInsight* service is a cloud-based service, powered by Apache Hadoop, that enables big data processing, ideal for ClickStream analysis. Given that the IIS logs for a deployed Gateway service are already located in *Microsoft Azure Blob Store* and this happens to be the default 'file system' of HDInsight, an optimized environment has been created to provide Application Analytics.

To enable Application Analytics for your Gateway Application, click on the **Analytics** tab. Check the **Enable Application Analytics** check-box and either select an existing HDInsight cluster or enter details for a new cluster. The **Node Count** value specifies how many 'data nodes' are provisioned in a new cluster. As a general rule, the greater the number of data nodes the faster results will be calculated. However, the cost of operating a HDInsight cluster is directly proportional to the number of data nodes and given that all analytics aggregate calculations will not be interactive with users adding more data nodes is not generally useful.

Click the **Apply** button. If a new HDInsight cluster has been selected to be created, the Management Console will deploy this via *Microsoft Azure*. Progress of this operation will be displayed on the screen. Additionally, jobs will be created in the *Microsoft Azure Scheduler* service (if enabled - see prerequisites section) to periodically invoke the HDInsight cluster to process the ClickStream logs and calculate pre-defined aggregate information.

Once Application Analytics has been enabled and there is sufficient information in the ClickStream logs, results of the analytics may be displayed as pre-defined charts. In the **Charting Analytics** section of the page, select one of the graph reports and click the **Show** button. Analytic information for that report will be rendered as a chart in the area below.
 
## Applying Updates to the Service Gateway and Management Console

The *Service Gateway* is a live project that is being continually updated. Features are available in the Management Console which allow new updates to be applied. Both the Service Gateway and the Management Console itself may be updated directly from the Management Console website.

A dedicated service provides the updated packages for the various pieces of software (Service Gateway or Management Console). This service also provides a mechanism for querying the availability of updates for a given version of the software. It also provides a description of an update as well as the criticality (e.g. if a security vulnerability has been identified and fixed). 

### Updating the Service Gateway

When a Service Gateway installation has been previously deployed by the Management Console, this information is recorded including the version number that was deployed. On the **Deployments** tab, the prior deployments are listed with additional information indicating if the current version can be updated.

If a new version is available click the **Update** link associated with the deployment to display the **Update Service Gateway Deployment** page. This page displays all details of the deployment that is to be updated together with a list of all available deployment packages. The list of available packages also includes prior versions which may be applied if a downgrade is required. Click the **Apply Update** link associated with the version that you wish to apply and the Management Console will take care of the rest - displaying status updates as the deployment progresses. All existing configuration for the Service Gateway (including number of instances, any SSL certificates and role configuration) is preserved for the newly updated version.

For existing Service Gateway deployments, the **Update** link may be clicked even if an updated package is not available. This option is useful if you wish to roll-back or downgrade a version or you simply want to re-deploy the current software.

### Updating the Management Console Website

The Management Console may also be updated as new features and/or bug fixes are made available. Every time you navigate to the Home page of the Management Console site, a check is performed to see if an updated version is available. If an update is available, a message will be displayed featuring an **Update Now** link that may be selected to update the website. The **Available Management Console Updates** page lists all available versions of the Management Console application. Click the **Apply Update** link associated with the version you wish to apply. The website will then apply the update 'in place' (i.e. the website is capable of updating itself using the same WebDeploy technology that was originally used to provision and deploy the website from the **Microsoft Azure Websites Gallery**. Applying the update will normally only take a few seconds, after which the application will automatically navigate back to the Home page.

Automatic update checks can be disabled for both the Service Gateway and Management Console by setting the `NoUpdateCheck` service configuration value to `True`.

### Bootstrapping Updating the Management Console Website

For all versions prior to v0.7 of the Management Console application, there is no facility to apply updates of any kind. This means that once the application is deployed from the Gallery, the software is frozen in time. From v0.7 onwards, the self-update capability described above will enable the Management Console to be upgraded (or downgraded) from any version to any version. 

Users of existing Management Console websites prior to v0.7 need a way to bootstrap to v0.7. To do this, follow these steps:

1. Delete the current website; *[myconsole].azurewebsites.net*. Prior to deleting the website, take note of the details of the database associated with the site - you will reconnect to this database later. When you delete the website from the **Microsoft Azure Portal**, take care NOT to delete this database.
2. Create a new Management Console website from the Gallery using the same name. Repeat the original steps in the **Microsoft Azure Portal** to create a Management Console website. In the Gallery page, select the **Tools** category and select the **Service Gateway Management Console** item. Verify that the **Version** is greater or equal to **0.7**. Click Next.
3. In the **URL** field, enter the exact same name that the previous Management Console had. Because you have already deleted this website the name should be available for use. In the **Database** drop-down, ensure that **Use an existing SQL database** is selected. Click Next.
4. On the **Database Settings** page, select the name of the database associated with the previous Management Console website using the details recorded in step 1. Enter the credentials for this database.
5. Click the OK button to provision a new version of the Management Console website and connect it to the existing database. 
6. Browse to the new/old Management Console website.
7. You will be guided through the welcome/initialization sequence to associate your **Azure Active Directory** Application information. Click the **Sign In To Continue** button as we will reuse the existing AAD Application from the prior version.  
8. In the **Microsoft Azure Portal**, navigate to the **Active Directory** section and select the Directory that you originally registered the Management Console Application.
9. Click the **Applications** tab and select the Application that was registered for the prior version Management Console website.
10. On the **Configure** tab. copy the **CLIENT ID** value to the clipboard. Switch back to the new Management Console **Step 2 of 2** page and paste this value in the **Client ID** field.
11. Switch back to the **AAD Portal**. If **REPLY URL** values does not include an address with the *https* protocol, then add this now (i.e. If you only have a REPLY URL value of 'http://myconsole.azurewebsites.net' then add a new value 'http**s**://myconsole.azurewebsites.net'). 
12. Create a new key (1 or 2 years). Click the **Save** button and copy the new key value to the clipboard when it is displayed. Switch back to the Management Console page and paste this value in the **Key Value** field. Click the **Complete Initialization** button.
13. Verify that the Role and Security configuration from the previous Management Console website is preserved. Also verify that prior Service Gateway deployments are displayed.

As subsequent updates are released, these will be notified and be available to update as described above. 
 

  
   
